Skip to content

docs(uipath-maestro-flow): move existing nodes from source .layout(); stale keys warn (SDK 6.115.0) - #4725

Merged
tmatup merged 4 commits into
mainfrom
docs/flow-merge-layout-edits
Nov 16, 2026
Merged

tmatup merged 4 commits into
mainfrom
docs/flow-merge-layout-edits

Conversation

@tmatup

@tmatup tmatup commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Lands after #4724 (stacked on it, which lands after #4723; same brownfield.md and diagnose.md passages).

The SDK change shipped: UiPath/builder-sdk#2037 is in @uipath/maestro-builder-sdk 6.115.0, and the docs name that version as the floor.

Short version

Two layout edits no longer need a hand edit of the merged .flow (UiPath/builder-sdk#2037):

  1. merge applies a changed .layout() entry (position, size or collapsed state differing from the baseline) to the original node, at the root and in subflows. Example: review: at(640, 144) changed to at(640, 304) moves only review.
  2. compile drops a .layout() key that names no step (or an edge key matching no edge) with a LAYOUT_UNKNOWN_KEY warning instead of refusing. check reports the same warning.

What text is retired, and why

  • references/brownfield.md: "Only an added step's entry lands" and "moving or resizing one in the source does nothing, so ... set layout.nodes.<id>.position or .size in the merged .flow" replaced with: change the entry in the source and merge. The subflow sentence now says a kept subflow also takes its changed entries (the subflow-layout-sdk-upgrade flavor block is unchanged). "A step the edit removes must lose its entry, or compile fails on the unknown key" now says the leftover key is dropped with a warning.
  • references/operate.md rule 3: "an unknown key fails compile" becomes "is dropped with a LAYOUT_UNKNOWN_KEY warning".
  • references/diagnose.md "Misshapen nodes": "In a merged brownfield file only an added node's entry lands; fix ... in the merged .flow's layout.nodes" becomes: fix it in the decompiled source and merge again.

No flavor block content changed; the Studio Web overrides already say never to edit the merged .flow.

Checks run

npm run skills:validate, npm run skills:check-links, git diff --check.

🤖 Generated with Claude Code
Co-Authored-By: Claude

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @tmatup's task in 1m 1s —— View job


PR Review: #4725

  • Read diff, review guide, and project rules
  • Read full context of brownfield.md, diagnose.md, operate.md
  • Check the studioweb flavor overrides, links and anchors, and searched for leftover old guidance
  • Post review

Summary

Updates the brownfield layout guidance for builder-sdk#2037. merge now applies a changed .layout() entry to the original node, so moving or resizing a node means editing the source and merging, with no hand edit of the merged .flow. A .layout() key that names no step is now dropped with a LAYOUT_UNKNOWN_KEY warning instead of failing compile.

Change-by-Change Review

1. skills/uipath-maestro-flow/references/brownfield.md:670-676

Medium: the new behaviour has no minimum SDK version.
Every other SDK-dependent behaviour in this file states its minimum version and what an older SDK does: the subflow sentence on line 672 (6.44.4 or later; an older SDK takes every subflow…), and lines 102, 266, 549 and 614–616. Line 671 and line 676 drop the old wording and give no version at all.

What goes wrong: an agent on an SDK older than the #2037 release changes review: at(640, 304), merges, and nothing moves. The text no longer mentions the old fallback (editing layout.nodes.<id>.position in the merged .flow), so the agent has no next step. Line 676 is also wrong on an older SDK, where a leftover key still fails compile.

Holding the merge until the SDK ships does not fix this, because users don't upgrade the SDK when the skill changes.

Fix: once the release version is known, add (<VERSION> or later; an older SDK keeps the original's geometry and fails compile on an unknown key…) with an SDK-upgrade flavor block. That matches subflow-layout-sdk-upgrade / dup-step-sdk-upgrade, and the studioweb flavor will need an override for it like the others have. Make the same change in operate.md:73 and diagnose.md:133. Fix this →

Everything else here is correct and terse:

  • The added-step sentence still reads well with its "Only an added step's entry lands" opener removed.
  • The subflow rewording keeps the subflow-layout-sdk-upgrade block in the same place, and the sentence still closes correctly.
  • The review: at(640, 144) → at(640, 304) example is concrete and useful.

2. skills/uipath-maestro-flow/references/operate.md:73

OK apart from the version gate in item 1. One thing to consider: rule 3 now gives the warning but no action. Adding "remove it" would match the "Remove the entry…" instruction in brownfield.md:676.

3. skills/uipath-maestro-flow/references/diagnose.md:133

OK. The line sits outside the misshapen-format block. The studioweb override of that block (skill-flavors/studioweb/.../diagnose.md:32-39) doesn't conflict, and studioweb builds get the new canonical line unchanged. Both anchors (#lay-out-from-source-instead-layout-at-dim, #the-same-loop-by-hand) resolve.

What's Missing

  • The minimum SDK version and older-SDK fallback described in item 1.
  • No eval task checks the new loop (move a node by editing its source entry, merge, check layout.nodes.<id>.position changed). tests/tasks/uipath-maestro-flow/_shared/check_brownfield_preserved.py already exists to build on. This is optional for a 6-line docs change.

No leftover text describing the old behaviour remains in the skill or the studioweb overrides. I searched for unknown key, only an added, layout.nodes and does nothing; the layout.nodes hits at operate.md:34-35 are about format, which is a different topic.

Area Ratings

Area Status Notes
Frontmatter OK Not touched
E2E Tests OK No new capability that needs a task; an optional one is suggested above
Skill Body OK SKILL.md not touched
References & Assets Issue Minimum SDK version and older-SDK behaviour missing (Medium)
Repo Hygiene OK Changes stay inside the one skill; no secrets or personal paths; links resolve

Issues for Manual Review

  • Check that fix(uipath-platform): stop traces feedback e2e from timing out #2037 really applies collapsed state changes, and that a decompiled source can express collapsed state in an at()/long-hand entry. Otherwise "position, size or collapsed state" promises something the agent can't do.
  • Check that an edge key matching no edge also only warns. The PR body says so, but the docs mention only node keys.
  • Check that check reports LAYOUT_UNKNOWN_KEY with that exact code, since agents will grep for it.

I didn't run npm run skills:validate / skills:build myself. No flavor block content changed, so the author's runs cover it.

@tmatup

tmatup commented Nov 14, 2026

Copy link
Copy Markdown
Member Author

Review triage (Claude bot):

🤖 Generated with Claude Code
Co-Authored-By: Claude

@tmatup
tmatup force-pushed the docs/flow-merge-placeholder-flag branch from 8670114 to 79af089 Compare November 15, 2026 00:27
@tmatup
tmatup requested review from a team and cezara98t as code owners November 15, 2026 00:27
@tmatup
tmatup force-pushed the docs/flow-merge-layout-edits branch from f74f74b to 7d3d3b5 Compare November 15, 2026 00:27

@rockymadden rockymadden left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Commented: no blockers of its own. It is stacked on #4724, which has one, and builder-sdk#2037 still shows changes requested.

What

Docs for builder-sdk#2037 (open, latest review is changes requested). Merge applies a changed .layout() entry to the original node, so moving a node no longer needs a hand edit of the merged .flow. A stale key now warns LAYOUT_UNKNOWN_KEY instead of failing compile. The older-SDK fallback sits in a new layout-edit-sdk-upgrade flavor block, and the Studio Web override says to tell the user.

Axes

Axis Blockers Non-blockers Top finding
Correctness & logic 0 2 entry may not exist after a new-SDK compile skills/uipath-maestro-flow/references/brownfield.md:619
Code quality & simplicity 0 0 none
Types & contracts 0 0 none
Tests & validation 0 0 none
Security 0 0 none
Architecture & design 0 0 none
Error handling & resilience 0 0 none
Interface, docs & compatibility 0 2 subflow sentence contradicts the move rule skills/uipath-maestro-flow/references/brownfield.md:624

Overall findings

  • None beyond the inline comments.

Verified vs reasoned

  • ✅ Checked at builder-sdk#2037 head 034b99dd: applyLayoutEdits runs only with a baseline, diffs position/size/collapsed, and covers root and subflows. Every documented loop has a baseline: stamped source, --baseline, or a compiled baseline for a supplied source (brownfield.md:306).
  • ✅ The flavor block reads as a sentence on both sides. Studio Web's "tell the user" fits its rule never to hand-edit the merged .flow.
  • ✅ LAYOUT_UNKNOWN_KEY is a warning in compile and check.
  • ❓ Not verified: whether the designer keeps ui.placeholder on a node when it saves, which decides how often the first inline finding hits.
  • ❓ #2037's last fix (flag every compiled node) has not been re-reviewed. Recheck these lines if it changes.

tl;dr

Matches the SDK on the canonical path. Four small fixes: the entry may not exist, Studio Web drops moves onto grid points, the gates need version numbers, and one subflow sentence contradicts the move rule.

@tmatup
tmatup force-pushed the docs/flow-merge-placeholder-flag branch from 79af089 to 1fe4269 Compare November 15, 2026 16:55
tmatup added a commit that referenced this pull request Nov 15, 2026
… kept subflow takes your changed entries

Review on #4725: decompile writes no .layout() entry for a node compile
placed, so the move instruction says change or add the entry; and a subflow
kept from the original still takes the entries you changed.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
@tmatup
tmatup force-pushed the docs/flow-merge-layout-edits branch from 7d3d3b5 to c29044a Compare November 15, 2026 16:55

@rockymadden rockymadden left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recommendation: 🟢 Approved. Three of four non-blockers are fixed at c29044ad; one stands.

Fixed

  • ✅ 🟡 "Change its entry" assumed one exists: now "change or add its entry … decompile writes none for a node compile placed and nobody moved since".
  • ✅ 🟡 Studio Web move onto a grid point dropped: builder-sdk#2036 marks every compiled node, and #2037 (f35b1b6c) passes the same unplacedRule to applyLayoutEdits (merge.ts:603-614), so the move lands.
  • ✅ 🟡 "Any other subflow keeps the original" contradicted the move rule: now "plus the entries you changed".

Still open

  • 🟡 PR-number gates: brownfield.md:625 and :633, diagnose.md:135, operate.md:81 say "builder-sdk#2037". Inline.

New: none. layout-edit-sdk-upgrade has its Studio Web override; LAYOUT_UNKNOWN_KEY as a warning matches serialize.ts at #2037's head.

Axes

Axis Blockers Non-blockers Top finding
Correctness & logic 0 0 none
Code quality & simplicity 0 0 none
Types & contracts 0 0 none
Tests & validation 0 0 none
Security 0 0 none
Architecture & design 0 0 none
Error handling & resilience 0 0 none
Interface, docs & compatibility 0 1 PR-number SDK gate skills/uipath-maestro-flow/references/brownfield.md:625

Not verified: I read the SDK heads, didn't run a merge.

tl;dr

  • Fixed except the PR-number gates. Swap them for the release version, then merge after #2037 ships.

@tmatup
tmatup force-pushed the docs/flow-merge-placeholder-flag branch from 1fe4269 to d852b78 Compare November 15, 2026 17:20
tmatup added a commit that referenced this pull request Nov 15, 2026
… kept subflow takes your changed entries

Review on #4725: decompile writes no .layout() entry for a node compile
placed, so the move instruction says change or add the entry; and a subflow
kept from the original still takes the entries you changed.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
@tmatup
tmatup force-pushed the docs/flow-merge-layout-edits branch from c29044a to 63152e3 Compare November 15, 2026 17:20
@tmatup
tmatup force-pushed the docs/flow-merge-placeholder-flag branch from d852b78 to 54d3b23 Compare November 15, 2026 22:30
tmatup added a commit that referenced this pull request Nov 15, 2026
… kept subflow takes your changed entries

Review on #4725: decompile writes no .layout() entry for a node compile
placed, so the move instruction says change or add the entry; and a subflow
kept from the original still takes the entries you changed.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
@tmatup
tmatup force-pushed the docs/flow-merge-layout-edits branch from b85f348 to ba46c05 Compare November 15, 2026 22:30
@tmatup tmatup changed the title docs(uipath-maestro-flow): move existing nodes from source .layout(); stale keys warn (merge after the SDK release that ships builder-sdk#2037) docs(uipath-maestro-flow): move existing nodes from source .layout(); stale keys warn (SDK 6.115.0) Nov 15, 2026
@tmatup
tmatup force-pushed the docs/flow-merge-placeholder-flag branch from 54d3b23 to 43aed58 Compare November 15, 2026 23:21
Base automatically changed from docs/flow-merge-placeholder-flag to main November 15, 2026 23:41
@tmatup
tmatup changed the base branch from docs/flow-merge-placeholder-flag to main November 15, 2026 23:41
… stale keys warn

Replayed onto the rebased #4724 (builder-sdk#2037), with the older-SDK
fallback.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
… kept subflow takes your changed entries

Review on #4725: decompile writes no .layout() entry for a node compile
placed, so the move instruction says change or add the entry; and a subflow
kept from the original still takes the entries you changed.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
…the whole scope is compile's

Matches builder-sdk#2035 e7ef8e63e: once any node of a laid-out flow or
subflow is moved, decompile writes every node's entry.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
…dits (6.115.0)

builder-sdk#2037 shipped in @uipath/maestro-builder-sdk 6.115.0. The Studio
Web override tells the user the version.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
@tmatup
tmatup force-pushed the docs/flow-merge-layout-edits branch from ba46c05 to 23255ec Compare November 15, 2026 23:42
@tmatup
tmatup merged commit d463015 into main Nov 16, 2026
48 checks passed
@tmatup
tmatup deleted the docs/flow-merge-layout-edits branch November 16, 2026 00:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants